h5ai im Docker: Schicke Dateiübersicht für Deinen Server

h5ai im Docker ist eine angenehm schlanke Möglichkeit, aus einem Ordner auf Deinem Server einen übersichtlichen Dateiindex, Web-Dateibrowser oder eine kleine Download-Plattform zu machen. Du legst Dateien in ein Verzeichnis, öffnest die Webseite und hast eine hübsche Oberfläche zum Stöbern, Sortieren und Herunterladen.

Ich mag solche Tools, weil sie nicht versuchen, gleich ein komplettes DMS, eine Cloud und einen Toaster zu ersetzen. h5ai macht genau eine Sache: Dateien im Browser sauber darstellen. Und das reicht in vielen Fällen völlig aus.

Das hier verwendete Docker-Image kommt von awesometic/docker-h5ai. Es bringt h5ai zusammen mit Nginx und PHP in einen Container und eignet sich damit sehr gut für Selfhosting-Setups, kleine Downloadbereiche oder interne Dateiablagen.

🧩 Voraussetzungen

Bevor es losgeht, brauchst du natürlich eine funktionierende Docker-Umgebung.
Wenn du Docker noch nicht installiert hast, findest du hier eine Schritt-für-Schritt-Anleitung, wie du das auf Ubuntu mit einem Script erledigst:

Sobald Docker läuft, brauchst du nur noch einen Ordner für das Projekt und einen freien Port. In meinem Beispiel nutze ich Port 4980. Den kannst du natürlich ändern, wenn dort bei dir schon etwas lauscht.

📁 Projektordner vorbereiten

Wir legen zuerst einen eigenen Ordner für h5ai an. Darin landet gleich die docker-compose.yaml und später auch die Freigabe mit den Dateien.

mkdir h5ai
cd h5ai
nano docker-compose.yaml

Die eigentlichen Dateien, die später im Browser sichtbar sind, liegen in diesem Beispiel unter ./shared/dir. Die Konfiguration von h5ai und Nginx landet unter ./config/dir.

⚙️ h5ai Docker Compose Datei

Für den Einstieg reicht eine übersichtliche Compose-Datei. Ich halte sie hier bewusst schlicht, damit du sie direkt nachvollziehen kannst.

services:
  h5ai:
    image: awesometic/h5ai:latest
    container_name: h5ai
    hostname: h5ai
    ports:
      - "4980:80"
    volumes:
      - ./shared/dir:/h5ai
      - ./config/dir:/config
    environment:
      PUID: "1001"
      PGID: "1001"
      TZ: Europe/Berlin
    restart: unless-stopped

Wichtig sind vor allem die beiden Volumes. Alles, was du unter ./shared/dir ablegst, erscheint später in h5ai. Der Ordner ./config/dir enthält die Konfiguration und sollte deshalb dauerhaft auf dem Host bleiben.

PUID und PGID richtig setzen

Bei PUID und PGID trägst du am besten den Benutzer ein, dem die Dateien auf dem Host gehören. Die Werte findest du mit:

id

Wenn du auf einem klassischen Docker-Host arbeitest, ist häufig 1000:1000 passend. In meinem Beispiel aus der Notiz stand 1001:1001. Nimm hier also nicht blind irgendeinen Wert, sondern prüfe kurz den Benutzer. Das dauert zehn Sekunden und spart später diese wunderbar unnötigen Rechteprobleme.

🚀 Container starten

Wenn die Compose-Datei gespeichert ist, startest du den Container ganz normal mit Docker Compose:

docker compose up -d

Danach lohnt sich ein kurzer Blick auf den Status und in die Logs:

docker compose ps
docker compose logs -f

Wenn alles passt, erreichst du h5ai anschließend unter:

http://SERVER-IP:4980

In einer produktiven Umgebung würde ich das Ganze natürlich hinter einen Reverse Proxy mit HTTPS hängen. h5ai selbst kümmert sich nicht um TLS. Das ist auch okay so, denn dafür sind Nginx Proxy Manager, Traefik oder Caddy deutlich besser geeignet.

📦 Dateien hochladen

h5ai braucht keine eigene Upload-Funktion. Du kopierst die Dateien einfach in den gemounteten Ordner auf dem Server. Das kann per scp, rsync, SFTP oder direkt über eine vorhandene Freigabe passieren.

mkdir -p shared/dir/Dokumente
cp beispiel.pdf shared/dir/Dokumente/

Sobald die Datei im Ordner liegt, taucht sie im Browser auf. Bei Bildern, Audio und Videos kann h5ai auch Vorschauen beziehungsweise passende Darstellungen erzeugen. Das wirkt direkt deutlich freundlicher als ein nacktes Apache-Directory-Listing aus der Kategorie „funktioniert, aber schön ist anders“.

🔐 Zugriff absichern

Wenn der Dateiindex öffentlich erreichbar ist, solltest du dir die Zugriffskontrolle sehr genau anschauen. Für interne Testsysteme ist offen manchmal okay. Für echte Dateien im Internet eher nicht. Überraschung: Menschen klicken Dinge an.

Das Image unterstützt optionalen htpasswd-Schutz über Umgebungsvariablen. Dafür kannst du die folgenden Variablen ergänzen:

environment:
  PUID: "1001"
  PGID: "1001"
  TZ: Europe/Berlin
  HTPASSWD: "true"
  HTPASSWD_USER: "download"
  HTPASSWD_PW: "bitte-aendern"

Noch besser ist es, wenn du den Zugriff zusätzlich über Deinen Reverse Proxy regelst. Gerade bei sensiblen Dateien würde ich h5ai nicht einfach offen ins Internet hängen. HTTPS ist Pflicht, denn Basic Auth ohne verschlüsselte Verbindung ist ungefähr so beruhigend wie ein Schloss aus Pappe.

🔄 Updates durchführen

Beim verwendeten Image ist vor allem der Tag latest relevant. Ein Update läuft daher klassisch über neues Image ziehen und Container neu erstellen:

docker pull awesometic/h5ai:latest
docker compose down
docker compose up -d

Vor größeren Änderungen würde ich den Ordner ./config/dir sichern, besonders wenn du h5ai optisch oder funktional angepasst hast. Der Entwickler weist ebenfalls darauf hin, dass bei Updates Konfigurationsdateien betroffen sein können. Backup ist hier keine Heldentat, sondern einfach gute Gewohnheit.

🧪 Mein kurzer Test

Ich habe den Container zum Testen mit ein paar Beispieldateien gefüttert: Dokumente, eine YAML-Datei, ein Logfile, ein Bild, eine MP3 und ein kleines Video. Genau daran sieht man gut, wofür h5ai gedacht ist: Du bekommst schnell eine brauchbare Dateiübersicht, ohne dafür gleich eine schwere Plattform aufzubauen.

Für öffentliche Downloads, interne Ablagen, temporäre Austauschordner oder kleine Projektarchive ist das ziemlich praktisch. Du solltest nur nicht vergessen, dass h5ai keine Benutzerverwaltung, kein Rechtesystem und keine Cloud-Synchronisierung ersetzt. Es ist ein schöner Dateiindex. Nicht mehr, aber eben auch nicht weniger.

🔗 Fazit

h5ai im Docker ist schnell eingerichtet und macht aus einem normalen Ordner eine saubere Download-Ansicht im Browser. Besonders sympathisch finde ich, dass die Lösung angenehm unspektakulär bleibt. Keine Benutzeroberfläche mit 47 Menüpunkten, kein Datenbank-Zirkus, kein Overhead.

Wenn du einfach Dateien bereitstellen möchtest und die Absicherung über Reverse Proxy, HTTPS und optional htpasswd sauber löst, ist h5ai eine wirklich runde Sache.

👥 Techniverse Community

Lust auf Austausch rund um Matrix, Selfhosting und andere smarte IT-Lösungen?
In der Techniverse Community triffst du Gleichgesinnte, kannst Fragen stellen oder einfach nerdigen Talk genießen. 🚀

👉 Jetzt der Gruppe auf Matrix beitreten
~ Direkte Raumadresse: #community:techniverse.net

👉 Für lockere Gespräche abseits der Kernthemen komm in den Talkraum
~ Direkte Raumadresse: #talk:techniverse.net

Wir freuen uns, wenn du dabei bist!